/*
 * Copyright 2007 Matt Jensen
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations under the License.
 */
package org.jtell;

/**
 * <p>
 * <code>EventChannel</code> defines the public interface to an event channel. An event channel is the core interface
 * through which an application registers and unregisters event listeners and publishes events for consumption by those
 * listeners.
 * </p>
 * <p>
 * Child event channels may also be created via this interface. Listeners registered with a child channel cannot see
 * events published with the parent channel, but listeners registered with the parent context <em>can</em> see events
 * published with the child channel. 
 * </p>
 */
public interface EventChannel
{
    /**
     * <p>
     * Create a child event channel.
     * </p>
     *
     * @return {@link EventChannel} instance.
     */
    EventChannel createChildChannel();

    /**
     * <p>
     * Publish an event to the listeners registered with this channel and with its parent channel.
     * </p>
     *
     * @param event the application event object.
     */
    void notifyListeners(Object event);

    /**
     * <p>
     * Register a single listener on this channel.
     * </p>
     *
     * @param listener the application listener object.
     */
    void registerListener(Object listener);

    /**
     * <p>
     * Unregister all listeners on this channel. 
     * </p>
     */
    void unregisterAllListeners();

    /**
     * <p>
     * Unregister a single listener on this channel.
     * </p>
     * 
     * @param listener the application listener object.
     */
    void unregisterListener(Object listener);
}
